在当今 AI 时代，经常依赖各种 AI 服务来获取信息和解决问题。然而，在某些场景下，使用云端 AI 服务可能存在以下问题：
隐私安全顾虑：
成本控制需求：
定制化需求：
本地 AI 解决方案主要由两个核心组件构成：
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 用户界面层 │───▶│ 应用服务层 │───▶│ 数据存储层 │
│ Web/API 接口 │ │ MaxKB 知识库 │ │ 文档/向量数据库 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ AI 模型层 │
│ Ollama 框架 │
└─────────────────┘核心组件说明：
硬件配置建议：
操作系统支持：
macOS 安装：
# 使用 Homebrew 安装
brew install --cask docker
# 或者从官网下载安装包
# https://www.docker.com/products/docker-desktop/Windows 安装：
Linux 安装（Ubuntu）：
# 更新包索引
sudo apt-get update
# 安装依赖包
sudo apt-get install \
ca-certificates \
curl \
gnupg \
lsb-release
# 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# 设置 Docker 仓库
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装 Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
# 验证安装
sudo docker run hello-world# 安装 Node.js（推荐 v22+ LTS）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证安装
node --version
npm --versionMaxKB 是一个开源的知识库管理系统，具有以下特点：
核心功能：
技术优势：
创建数据目录：
# 创建 MaxKB 数据存储目录
mkdir -p ~/.maxkb
cd ~/.maxkb
# 创建 Python 包目录（用于沙箱环境）
mkdir -p python-packages配置 Docker 网络（可选）：
# 创建专用网络
docker network create maxkb-network步骤 1：拉取 MaxKB 镜像
docker pull cr2.fit2cloud.com/1panel/maxkb:latest步骤 2：运行 MaxKB 容器
docker run -d \
--name=maxkb \
--restart=always \
-p 8080:8080 \
-v ~/.maxkb:/var/lib/postgresql/data \
-v ~/.maxkb/python-packages:/opt/maxkb/app/sandbox/python-packages \
-e MAXKB_DB_TYPE=postgresql \
-e MAXKB_DB_HOST=localhost \
-e MAXKB_DB_PORT=5432 \
-e MAXKB_DB_NAME=maxkb \
-e MAXKB_DB_USER=maxkb \
-e MAXKB_DB_PASSWORD=MaxKB@123.. \
cr2.fit2cloud.com/1panel/maxkb:latest注意：MaxKB 迭代较快，镜像地址、环境变量等部署细节请以 官方文档 为准。
步骤 3：验证部署
# 检查容器状态
docker ps | grep maxkb
# 查看容器日志
docker logs maxkb
# 访问 Web 界面
open http://localhost:8080默认登录信息：
adminMaxKB@123..创建知识库：
文档上传配置：
支持的文档格式：
文本格式：.txt, .md, .json, .xml
文档格式：.pdf, .doc, .docx
表格格式：.xls, .xlsx, .csv
网页格式：.html, .htm高级配置选项：
Ollama 是一个开源的大模型本地运行框架，支持多种主流开源模型：
核心特性：
架构优势：
安装 Ollama：
macOS：
# 使用 Homebrew 安装
brew install ollama
# 或者下载安装包
# https://ollama.com/downloadLinux：
# 一键安装脚本
curl -fsSL https://ollama.com/install.sh | sh
# 手动安装
sudo curl -L https://ollama.com/download/ollama-linux-amd64 -o /usr/bin/ollama
sudo chmod +x /usr/bin/ollama常用模型推荐：
| 模型名称 | 参数规模 | 适用场景 | 硬件要求 |
|---|---|---|---|
| qwen2.5:0.5b | 5 亿 | 简单问答 | 4GB RAM |
| qwen2.5:1.5b | 15 亿 | 通用对话 | 8GB RAM |
| qwen2.5:7b | 70 亿 | 复杂任务 | 16GB RAM |
| llama2:7b | 70 亿 | 英文场景 | 16GB RAM |
| codeqwen:7b | 70 亿 | 代码生成 | 16GB RAM |
模型安装命令：
# 安装轻量级中文模型
ollama run qwen2.5:1.5b
# 安装更大的模型
ollama run qwen2.5:7b
# 查看已安装模型
ollama list
# 删除不需要的模型
ollama rm 模型名称启动 API 服务：
# 启动 Ollama 服务（默认端口 11434）
ollama serve
# 后台运行（Linux/macOS）
nohup ollama serve > ollama.log 2>&1 &API 调用测试：
# 基本对话接口测试
curl http://localhost:11434/api/chat -d '{
"model": "qwen2.5:1.5b",
"messages": [
{ "role": "user", "content": "你好，请介绍一下自己" }
],
"stream": false
}'
# 流式响应测试
curl http://localhost:11434/api/chat -d '{
"model": "qwen2.5:1.5b",
"messages": [
{ "role": "user", "content": "写一首关于秋天的诗" }
],
"stream": true
}'Node.js 调用示例：
// ollama-client.js
import axios from "axios"
class OllamaClient {
constructor(baseURL = "http://localhost:11434") {
this.baseURL = baseURL
}
async chat(model, messages, options = {}) {
const response = await axios.post(`${this.baseURL}/api/chat`, {
model,
messages,
stream: options.stream || false,
temperature: options.temperature || 0.7,
max_tokens: options.max_tokens || 2048
})
return response.data
}
async *streamChat(model, messages, options = {}) {
const response = await fetch(`${this.baseURL}/api/chat`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
model,
messages,
stream: true,
temperature: options.temperature || 0.7
})
})
const reader = response.body.getReader()
const decoder = new TextDecoder()
while (true) {
const { done, value } = await reader.read()
if (done) break
const chunk = decoder.decode(value)
const lines = chunk.split("\n").filter((line) => line.trim())
for (const line of lines) {
try {
const data = JSON.parse(line)
if (data.message) {
yield data.message.content
}
} catch (e) {
// 忽略解析错误
}
}
}
}
}
// 使用示例
const client = new OllamaClient()
// 非流式调用
const response = await client.chat("qwen2.5:1.5b", [
{ role: "user", content: "介绍一下机器学习" }
])
console.log(response.message.content)
// 流式调用
for await (const chunk of client.streamChat("qwen2.5:1.5b", [
{ role: "user", content: "写一段 Python 代码" }
])) {
process.stdout.write(chunk)
}在 MaxKB 中添加 Ollama 模型：
显示名称: 本地Qwen模型
模型类型: Ollama
模型名称: qwen2.5:1.5b
API域名: host.docker.internal:11434 # Docker容器访问宿主机
API密钥: 任意值（Ollama不需要认证）
最大token数: 2048
温度参数: 0.7注意事项：
host.docker.internal 而不是 localhost，因为 MaxKB 运行在 Docker 容器中创建智能问答应用：
进入"应用"页面，点击"创建应用"
填写应用基本信息：
关联知识库：
高级配置选项：
{
"temperature": 0.7,
"max_tokens": 2048,
"top_p": 0.9,
"frequency_penalty": 0.1,
"presence_penalty": 0.1,
"retrieval_config": {
"similarity_threshold": 0.7,
"top_k": 5,
"rerank": true
}
}获取应用 API 信息：
在应用概览页面可以找到：
http://localhost:8080/api/application/xxx）Node.js 调用示例：
// maxkb-client.js
import axios from "axios"
class MaxKBClient {
constructor(appId, apiKey, baseURL = "http://localhost:8080") {
this.appId = appId
this.apiKey = apiKey
this.baseURL = baseURL
}
async chat(message, options = {}) {
const response = await axios.post(
`${this.baseURL}/api/application/${this.appId}/chat`,
{
message,
stream: options.stream || false,
temperature: options.temperature || 0.7
},
{
headers: {
Authorization: `Bearer ${this.apiKey}`,
"Content-Type": "application/json"
}
}
)
return response.data
}
async *streamChat(message, options = {}) {
const response = await fetch(
`${this.baseURL}/api/application/${this.appId}/chat`,
{
method: "POST",
headers: {
Authorization: `Bearer ${this.apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
message,
stream: true,
temperature: options.temperature || 0.7
})
}
)
const reader = response.body.getReader()
const decoder = new TextDecoder()
while (true) {
const { done, value } = await reader.read()
if (done) break
const chunk = decoder.decode(value)
const lines = chunk.split("\n").filter((line) => line.trim())
for (const line of lines) {
try {
const data = JSON.parse(line)
if (data.content) {
yield data.content
}
} catch (e) {
// 忽略解析错误
}
}
}
}
}
// 使用示例
const client = new MaxKBClient("your-app-id", "your-api-key")
// 测试知识库问答
async function testKnowledgeBase() {
console.log("测试知识库问答...\n")
const questions = [
"艾米莉的朋友是谁？",
"卢卡斯有什么特点？",
"这个故事发生在什么季节？",
"小说的结局是什么？"
]
for (const question of questions) {
console.log(`问：${question}`)
console.log("答：")
for await (const chunk of client.streamChat(question)) {
process.stdout.write(chunk)
}
console.log("\n" + "=".repeat(50) + "\n")
}
}
testKnowledgeBase()应用场景：
实现步骤：
# 创建小说文档目录
mkdir ~/novels
cd ~/novels
# 创建示例小说（如前面的秋日秘密.txt）
cat > 秋日的秘密.txt << 'EOF'
秋天的午后，阳光透过金黄的树叶洒在小镇的石板路上...
EOF上传到知识库：
创建问答应用：
测试功能：
// 小说助手测试脚本
const client = new MaxKBClient(appId, apiKey)
// 人物分析
await client.chat("分析一下艾米莉这个人物的性格特点")
// 情节理解
await client.chat("这个故事的主题是什么？")
// 创意续写
await client.chat("请为这个故事续写一个温暖的结局")
// 细节问答
await client.chat("艾米莉第一次发现石亭是什么时候？")应用场景：
实施步骤：
文档整理：
知识库构建：
系统集成：
持续优化：
应用场景：
实现方案：
组件文档准备：
知识库配置：
代码生成提示词：
const promptTemplate = `
你是一个资深前端开发工程师，熟悉公司的内部组件库。
请根据以下需求生成代码：
用户需求：{user_request}
要求：
1. 使用内部的组件库
2. 遵循代码规范
3. 提供完整的示例
4. 添加必要的注释
相关文档：
{retrieved_docs}
请生成代码：
`模型选择策略：
硬件加速配置：
# 启用 GPU 加速（需要 NVIDIA GPU）
export OLLAMA_NUM_GPU=1 # 使用的 GPU 数量
export OLLAMA_FLASH_ATTENTION=1 # 启用 Flash Attention
export OLLAMA_KV_CACHE_TYPE=q8_0 # KV 缓存量化模型量化选项：
# 下载量化模型（更小更快）
ollama run qwen2.5:7b-instruct-q4_K_M # 4位量化
ollama run qwen2.5:7b-instruct-q8_0 # 8位量化文档预处理：
# 文档优化建议
def optimize_document(content):
# 1. 清理格式
content = clean_formatting(content)
# 2. 结构化处理
content = add_structure(content)
# 3. 关键信息提取
keywords = extract_keywords(content)
# 4. 添加元数据
metadata = {
'title': extract_title(content),
'author': extract_author(content),
'date': extract_date(content),
'keywords': keywords
}
return content, metadata检索优化：
性能监控：
// 性能监控脚本
class PerformanceMonitor {
constructor() {
this.metrics = {
queryTime: [],
tokenCount: [],
memoryUsage: [],
errorRate: []
}
}
recordQuery(startTime, endTime, tokenCount) {
this.metrics.queryTime.push(endTime - startTime)
this.metrics.tokenCount.push(tokenCount)
}
getAverageQueryTime() {
const times = this.metrics.queryTime
return times.reduce((a, b) => a + b, 0) / times.length
}
generateReport() {
return {
averageQueryTime: this.getAverageQueryTime(),
totalQueries: this.metrics.queryTime.length,
averageTokens: this.getAverageTokenCount(),
errorRate: this.calculateErrorRate()
}
}
}健康检查脚本：
#!/bin/bash
# health-check.sh
echo "=== 本地 AI 系统健康检查 ==="
# 检查 Docker 服务
echo "检查 Docker 服务..."
if ! docker info > /dev/null 2>&1; then
echo "❌ Docker 服务未运行"
exit 1
fi
echo "✅ Docker 服务正常"
# 检查 MaxKB 容器
echo "检查 MaxKB 容器..."
if ! docker ps | grep maxkb > /dev/null; then
echo "❌ MaxKB 容器未运行"
exit 1
fi
echo "✅ MaxKB 容器正常"
# 检查 Ollama 服务
echo "检查 Ollama 服务..."
if ! curl -s http://localhost:11434/api/tags > /dev/null; then
echo "❌ Ollama 服务未响应"
exit 1
fi
echo "✅ Ollama 服务正常"
# 检查模型状态
echo "检查模型状态..."
MODEL_COUNT=$(curl -s http://localhost:11434/api/tags | jq '.models | length')
if [ "$MODEL_COUNT" -eq 0 ]; then
echo "⚠️ 未安装任何模型"
else
echo "✅ 已安装 $MODEL_COUNT 个模型"
fi
echo "=== 检查完成 ==="日志管理：
# 日志收集脚本
#!/bin/bash
LOG_DIR="$HOME/ai-logs/$(date +%Y%m%d)"
mkdir -p "$LOG_DIR"
# 收集 Docker 日志
docker logs maxkb > "$LOG_DIR/maxkb.log" 2>&1
# 收集 Ollama 日志
cp ~/ollama.log "$LOG_DIR/" 2>/dev/null || echo "Ollama 日志不存在"
# 收集系统信息
docker system df > "$LOG_DIR/docker-system.log"
docker stats --no-stream > "$LOG_DIR/docker-stats.log"
echo "日志已保存到: $LOG_DIR"自动备份：
#!/bin/bash
# backup.sh
BACKUP_DIR="$HOME/ai-backups"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="maxkb-backup-$DATE.tar.gz"
mkdir -p "$BACKUP_DIR"
# 备份 MaxKB 数据
tar -czf "$BACKUP_DIR/$BACKUP_FILE" \
-C ~/.maxkb .
# 保留最近7天的备份
find "$BACKUP_DIR" -name "maxkb-backup-*.tar.gz" -mtime +7 -delete
echo "备份完成: $BACKUP_FILE"Q1: Docker 容器无法启动怎么办？
A: 检查以下常见问题：
docker infonetstat -an | grep 8080ls -la ~/.maxkbdocker logs maxkbQ2: Ollama 模型下载失败如何处理？
A: 尝试以下解决方案：
Q3: 知识库检索效果不佳如何优化？
A: 优化建议：
Q4: 系统响应速度慢如何提升？
A: 性能优化方法：
Q5: API 调用出现认证错误？
A: 检查认证配置：
Q6: 如何处理中文乱码问题？
A: 编码问题解决方案：
Q7: 模型推理结果不准确怎么办？
A: 准确性提升方法：
Q8: 如何扩展系统以支持更多用户？
A: 扩展方案：
数据安全：
系统安全：
模型安全：
网络安全：
# 配置防火墙（Ubuntu）
sudo ufw allow 8080/tcp # MaxKB
sudo ufw allow 11434/tcp # Ollama
sudo ufw enable
# 配置 Nginx 反向代理（可选）
server {
listen 80;
server_name your-domain.com;
location /maxkb/ {
proxy_pass http://localhost:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /ollama/ {
proxy_pass http://localhost:11434/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}官方文档：
开源项目：
学术论文：
社区资源：
文档版本信息：
贡献指南： 欢迎提交 Issue 和 Pull Request 来改进本文档。如有问题或建议，请联系维护团队。
免责声明： 本文档仅供学习和研究使用，请确保遵守相关法律法规和软件许可协议。